Rename File

PATCH/api/v1/users/me/files/:id/metadata

Renames an attachment the patient uploaded. Patients cannot rename attachments uploaded by staff. The rename updates the DB fileName only — the underlying GCS object is not relocated.

cv-api-key + Bearer accessToken

Productionhttps://api.care360-next.carevalidate.com/api/v1/users/me/files/{id}/metadata

Staginghttps://api-staging.care360-next.carevalidate.com/api/v1/users/me/files/{id}/metadata

note

Renames are display-only. They change the visible label and the value used in the next download URL's filename, but do not relocate the underlying bucket object.

Headers

Headers

cv-api-keystringrequired

Your unique API key for authentication.

Authorizationstringrequired

Bearer access token from /verify-otp.

Content-Typestringrequired

Must be application/json.

Path Parameters

Path Parameters

idstringrequired

Attachment UUID.

Request Body

Body

fileNamestringrequired

New display file name. Length 1–255. Required — an empty body returns 400.

Example: renamed.pdf

Behavior

The handler returns 404 VALIDATION_ERROR "File not found" if any of the following is true:

• Not found, or isDeleted === true.
• case.submitterId !== userId (not the patient's case).
• case.organizationId !== organizationId (wrong tenant).
• uploadedById !== userId — patients can only rename attachments they uploaded, not ones uploaded by staff.

The 404 is uniform — clients cannot tell which condition fired. This prevents the patient from probing whether an id refers to a staff-uploaded attachment.

Response Shape

See Files Overview › Attachment Object Shapes — same as list/metadata.

Example Request

cURL

curl -X PATCH '<BASE_URL>/api/v1/users/me/files/<id>/metadata' \
-H 'cv-api-key: <redacted>' \
-H 'Authorization: Bearer <accessToken>' \
-H 'Content-Type: application/json' \
-d '{ "fileName": "renamed.pdf" }'

JavaScript

const response = await fetch(
'<BASE_URL>/api/v1/users/me/files/<id>/metadata',
{
  method: 'PATCH',
  headers: {
    'cv-api-key': '<redacted>',
    'Authorization': 'Bearer <accessToken>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ fileName: 'renamed.pdf' }),
}
);
const data = await response.json();
console.log(data);

Python

import requests

response = requests.patch(
  '<BASE_URL>/api/v1/users/me/files/<id>/metadata',
  headers={
      'cv-api-key': '<redacted>',
      'Authorization': 'Bearer <accessToken>',
      'Content-Type': 'application/json',
  },
  json={'fileName': 'renamed.pdf'},
)
print(response.json())

Responses

▶200Success

{
  "status": 200,
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "fileName": "renamed.pdf",
    "isPHI": false,
    "isRestricted": false,
    "caseId": "550e8400-e29b-41d4-a716-446655440111",
    "uploadedBy": {
      "id": "550e8400-e29b-41d4-a716-446655440222",
      "firstName": "Jane",
      "lastName": "Doe"
    },
    "createdAt": "2026-04-30T12:34:56.000Z"
  }
}

▶400Validation errorcv-api-key missing, id not a UUID, fileName empty/too long, or body has no fileName.

{
  "status": 400,
  "success": false,
  "error": "At least one field must be provided for update",
  "code": "VALIDATION_ERROR"
}

▶401Authentication failure

{
  "status": 401,
  "success": false,
  "error": "Invalid or expired token",
  "code": "VALIDATION_ERROR"
}

▶404File not foundUniform across not-found, soft-deleted, wrong-owner, wrong-tenant, or wrong-uploader.

{
  "status": 404,
  "success": false,
  "error": "File not found",
  "code": "VALIDATION_ERROR"
}

Try It Out

Try itAPI Playground

▶